Chapter 07 · StoryCam Development Session
核心分镜依赖链与 Seedance 视频闭环
这一章记录 StoryCam 从“页面能生成图”推进到“剧本、资产图、9 帧分镜和视频生成彼此有明确依赖”的一次关键工程收敛。
本 Session 摘要
- 围绕 StoryCam 的核心创作链路，连续修复了 story-world 资产图生成、核心分镜生成、扩展分镜布局、轮询节奏和多组生成导致的 500 问题。
- 产品方向从“1/2/3 组核心分镜”收敛为 MVP 单组 15 秒短片，目的是适配 Seedance 2.0 单次生成的节奏和第一版产品复杂度。
- 明确了分镜脚本和所有分镜图必须依赖 story-world 中已确认的剧本、角色资产、场景资产，以及角色/场景资产图，不能脱离资产重新生成。
- 识别并修复了“未启用资产图参考”的根因：Inference.sh 的
openai/gpt-image-2支持prompt + images[]，但项目 adapter 尚未透传多图参考。 - 最终接上了 Seedance 视频生成的关键后端链路：生成 clip prompt packet、提交 Seedance task、轮询 task id、下载
content.video_url并存储为generated_clip。
时间线
“/api/story-world/assets/generate-images 这个接口报错 500；storycam/story-world 这个板块点击生成全部资产的时候。”
“重试了一次，现在一直显示生成中，是确实接口返回慢呢，还是什么原因？”
先从接口错误和 UI 卡在“生成中”切入，判断问题不只是响应慢，而是异步生图任务、轮询状态和失败态之间的边界不清楚。后续工作开始围绕“任务状态必须可恢复、可解释、可轮询”展开。
这成为后面所有 image job 设计的前提：接口不能因为上游未 ready 而 500；前端也不能把所有异常都表现成无限生成中。
“现在选择 2 组或者 3 组生成核心分镜，接口会报 500。”
问题从单个资产图接口扩大到核心分镜流程。Codex 需要检查 /api/storyboard 的输入、分组数量、分镜脚本结构和核心图生成之间的关系，避免 2/3 组路径产生未处理的后端异常。
后续产品决策把 MVP 收敛为单组 15 秒，既降低第一版交互复杂度，也减少多组数据结构和视频生成的倍增风险。
“现在点击 2 组后，到了核心分镜页，有几个问题：页面布局如图混乱排布；没有两个核心分镜图片的生成……应该调用文本模型生成分镜脚本，然后根据分镜脚本生成一张核心的分镜图。”
这一节点明确了核心业务逻辑：核心分镜图不是临时 prompt 直接生成，而是来自分镜脚本的第一帧。Codex 将 core storyboard 重新建模为“先有 9 帧结构化脚本，再有 frame 01 主图，再扩展 frame 02-09”。
核心分镜页从“展示多个临时组卡片”转向“展示 1 组 9 帧分镜体系”，为后面的扩展画布和视频 prompt packet 打基础。
“点击扩展分镜图后，这个轮询节奏太密了，需要一个合理的策略，你根据整个生图服务的经验。”
用户通过 Network 截图指出了轮询风暴。Codex 将扩展图生成改为使用已有 generation job 轮询策略，而不是对多个 frame 做高频重复请求。
后续测试计划中加入“Network 中不出现高频轮询风暴”，轮询策略成为生图体验稳定性的验收项。
“storycam/core-storyboard 这个板块的业务逻辑和交互逻辑需要迭代……根据组数生成对应组的分镜脚本……每组脚本固定 9 帧……点击中心图，再根据第 2-9 帧生成周围 8 张图。”
用户给出第一份完整改造计划。Codex 执行后端 schema、OpenRouter storyboard prompt、expand API、frame regenerate API 和前端画布交互的迭代，并保留旧字段兼容。
StoryCam 的核心分镜阶段拥有了完整 9 帧结构，不再把扩展卡当作 mock fixture；每张图都能按 frameNumber 找到对应脚本和重生成入口。
“你起下服务。”
“需要查看下 seedance2.0 一次请求能生成多长的视频。”
这一步把本地调试和模型能力边界连起来。Seedance 2.0 的生成时长约束影响了产品范围：如果 MVP 要顺利走通真实视频生成，就不能先做多组长视频工作台。
产品策略转向“单组、15 秒内、一条私人短片”，后续所有 storyboard、expand、video clip 的默认逻辑都围绕这个约束收敛。
“为了第一版 mvp 产品顺利迭代，做些调整：storycam/story-world，去掉 2 组和 3 组的生成按钮，只支持 1 组；storycam/core-storyboard，就做一组，控制 15s 内……”
“拓展的分镜图，是可以点击放大查看的。”
用户将产品从可变多组收敛成 MVP 单组路径，并明确扩展画布的视觉与交互：首次只显示中心图，点击后动效展开，未出图时显示等待框，右侧显示完整脚本摘要，ready 图可放大查看。
提交 64e6feb 完成 MVP 收敛：单组 15 秒、9 帧画布、story-world 批量生图、session restore、OpenRouter storyboard provider、Inference.sh image provider 基础设施。
“要及时 commit。”
“storycam/story-world 板块生成的角色资产和场景资产，是 core-storyboard 所有分镜生成的基础……分镜脚本是 storycam/story-world 中剧本改编的，也是一个依赖的 workflow。”
用户把依赖关系讲清楚：分镜脚本、核心图、扩展图都不能脱离 story-world 的已确认剧本和资产图。Codex 将 storyboard image 生成改为强制加载 StoryWorldVisualContext，并阻止纯文本兜底。
提交 be1367d 和 739f23f：缺资产图时返回 waiting_for_asset_images；provider 不支持参考图时返回 reference_images_unsupported；补充 API、服务和 E2E 测试。
“为什么核心分镜这里显示……未启用资产图参考？”
“你认真看这个文档，是支持图生图的……需要找到多个图片参考输入 + 文本输入最终生图的接口。”
Codex 起初解释为 provider factory 故意阻断纯文本兜底。用户指出 Inference.sh 文档已经支持图生图。Codex 重新核对官方 skill，确认 openai/gpt-image-2 支持 prompt + images[]。
根因定位为项目 adapter 未透传 images 字段，而不是模型能力不支持。提交 0293813 接上 Inference.sh 多图参考，核心/扩展分镜图可用角色和场景资产图作为视觉参考生成。
“你再梳理下整个环节的依赖关系，从剧本生成、资产图 -> 分镜脚本、核心分镜图 -> 分镜图拓展 -> 视频生成。”
Codex 梳理出完整链路：用户输入生成 story-world 文本资产；资产图锁定视觉；分镜脚本改编剧本和资产；核心图来自 frame 01；扩展图来自 frames 02-09；视频生成需要 clip prompt packet。
明确下一轮 5 点计划：storyboard 前置依赖门、depends_on_json 完整化、图像 job 依赖 media id、视频前置 packet、Seedance runner 真正接上。
“好的，继续完成这 5 点计划。”
Codex 以 incremental implementation、TDD 和 API/interface design 三条原则推进：先让 /api/storyboard 在资产图未 ready 时阻断；再扩展 clip prompt packet；最后接 Seedance 两段式提交和轮询。
提交 1a64a3b：后端依赖链完成闭环。验证通过 pnpm typecheck 和 7 个 focused test 文件共 42 个测试。
关键时刻
1. 从多组工作台收敛到单组 15 秒 MVP
问题：2/3 组生成引发 500、页面布局混乱，并且会放大分镜、资产图和视频生成的复杂度。
为什么重要：第一版产品要证明“私人想法到真实短片”的主路径，而不是先做完整导演工作台。
处理：Story world 去掉 2/3 组按钮，服务端也强制归一为 1 组、15 秒内，后续 Seedance 单次调用更可控。
2. 分镜图必须依赖 story-world 资产图
问题：如果核心图和扩展图只用文本 prompt，会重新发明人物和场景，破坏用户刚确认的 story-world。
为什么重要：StoryCam 的核心体验是“私人记忆世界的一致性”，角色、服装、道具、地点必须被锁住。
处理：新增 StoryWorldVisualContext，要求角色/场景资产图 ready 后才提交 storyboard image job；缺图返回等待态，不偷偷纯文本兜底。
3. “未启用资产图参考”的根因不是模型，而是 adapter
问题：UI 显示 provider 不支持资产图参考，用户指出 Inference.sh 文档明明支持图生图。
为什么重要：如果误判 provider 能力，会让产品停在 placeholder，真实链路无法验证。
处理：核对 Inference.sh 官方 skill 后，确认 openai/gpt-image-2 接受 images[]；项目 adapter 增加多图 URL 透传，并标记支持 reference images。
4. 视频生成不只是按钮，而是 packet + job + provider result
问题：早期 generate-clip 只创建 video job，Seedance provider runner 还没真正接上。
为什么重要：没有 provider task id、轮询和下载存储，就无法形成从 storyboard 到真实视频的闭环。
处理：clip prompt packet 纳入 9 帧摘要和分镜图 media reference；Seedance provider 支持 submit/resolve；轮询成功后下载 provider 视频并创建 generated_clip。
工程证据
64e6feb feat: converge storycam storyboard mvp — 单组 15 秒 MVP、9 帧画布、story-world 批量生图、session restore、Storyboard provider 和 Inference.sh 基础设施。be1367d feat: require story world assets for storyboard images — 强制核心/扩展分镜图依赖 story-world 资产图；加入等待和 provider 不支持参考图的 placeholder reason。739f23f test: cover storyboard asset-image waiting state — 补充文档和 E2E，覆盖资产图未 ready 的等待状态。0293813 feat: enable inference storyboard reference images — Inference.sh adapter 支持 images[]，Storyboard image provider 透传角色/场景 signed URL。签名 URL 内容在文档中按 [REDACTED] 处理。1a64a3b feat: enforce storycam generation dependencies — 完成 5 点依赖链计划，接上 storyboard 前置门、clip prompt packet、Seedance submit/resolve 和视频下载落库。pnpm typecheck 通过；focused Vitest 通过，包括 tests/api/storyboard.test.ts、tests/api/expansion.test.ts、tests/api/generationJobs.test.ts、src/lib/providers/seedance/videoProvider.test.ts、src/server/storycam/clipPromptPacketService.test.ts、src/server/storycam/videoGenerationService.test.ts、src/features/storycam/domain/artifactSchemas.test.ts，共 42 个测试。src/server/storycam/storyboardService.ts、src/server/storycam/storyboardImageService.ts、src/server/storycam/clipPromptPacketService.ts、src/server/storycam/generationJobService.ts、src/lib/providers/inferenceSh/imageProvider.ts、src/lib/providers/seedance/videoProvider.ts、docs/generated/api-contract.md、docs/references/providers.md。对外讲解用总结
这一段开发的重点，是把 StoryCam 从“几个页面能触发 AI 生成”推进成一个真正有依赖秩序的创作系统。我们先遇到的是接口 500、页面卡生成中、2/3 组布局混乱、扩展轮询过密这些表层问题；继续往下追，发现根问题是工作流还没把剧本、角色资产、场景资产、资产图、9 帧分镜脚本、分镜图和视频生成串成一条可靠链路。于是产品上先收敛为单组 15 秒 MVP，工程上让分镜脚本依赖 story-world，分镜图依赖资产图和 frame 脚本，视频生成依赖 9 帧 packet 和已生成的分镜图参考。这个 session 的价值在于：它把 StoryCam 的“私人故事世界”变成后续每一步生成都必须尊重的事实来源，也让 Seedance 2.0 从一个未来 provider 变成了可以通过 job 轮询、下载、落库的真实后端闭环。
后续事项
- MVP 收敛为 1 组、15 秒内、9 帧脚本。
- 核心/扩展分镜图强制依赖角色和场景资产图。
- Inference.sh 多图参考输入接入。
- Clip prompt packet 包含 9 帧摘要和 storyboard image media references。
- Seedance task 提交、轮询、下载和
generated_clip落库链路接上。
- 真实 Seedance 2.0 账号和模型配置下的端到端 smoke 结果。
- 含人物参考图进入 Seedance 的平台审核限制和可用素材策略。
- 本地服务启动和浏览器实际操作中的最新 UI 状态，需结合下一轮截图或录屏确认。
- 是否需要将 “资产图未 ready” 在前端变成更主动的引导，而不只是错误或占位。
- 跑一次真实 provider 全链路：story-world、资产图、核心图、扩展图、Seedance clip。
- 补 Seedance 失败、审核拒绝、超时、重拍这一段的前端恢复路径。
- 将生成成功的视频片段连接到 final work 合成与预览确认流程。
- 继续检查轮询退避、任务取消、late result discard 和成本控制策略。